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AE9/AP9/SPM  Model  Program  Overview 

This  delivery  contains  all  files  needed  to  install  and  execute  the  C++-based  AE9/AP9/SPM 
Radiation  Environment  model,  using  a  command-line  program  execution,  or  through  a  graphical 
user  interface  (GUI). 

The  Command-Line  program  ‘CmdLineAe9Ap9  .  exe’  reads  model  parameters  and  orbit 
specifications  from  user-constructed  input  files  and  produces  the  requested  set  of  files  containing 
flux  and  fluence  calculation  results.  Dose  calculation  results  are  also  available. 

The  GUI  program  ‘testAe9Ap9Gui  .  exe’  provides  a  graphical  user  interface  to  specify  an 
orbital  path  and  various  model  parameters  in  a  user-friendly  format.  The  GUI  program  executes 
the  CmdLineAe9Ap9  program  using  the  input  files  automatically  generated  according  to  the 
user’s  selections  in  the  interface.  Basic  2D  plots  of  the  model  results  may  also  be  produced. 


AE9/AP9  Code  Stack 

Graphical  User  Interface 

-User-friendly  access  to  AE9/AP9,  and  other  models,  with  basic  graphical  outputs 

High-level  Utility  Layer 

-Command  line  interface  for  producing  mission  statistics 
Aggregates  results  of  many  MC  scenarios  (flux,  fluence,  mean,  percentiles) 
Provides  access  to  orbit  propagator  and  other  models  (e.g.  AP8/AE8,  CRRES) 
Provides  dose  rate  and  dose  for  user-specified  thicknesses  (ShieldDose-2) 

Application  Layer 

-Simple  C-H-  interface  to  single  Monte-Carlo  scenario  "flyin()"  routines 

AP9/AE9  Model  Layer 

-Main  workhorse;  manages  database  access,  coordinate  transforms  and  Monte 
Carlo  cycles;  error  matrix  manipulations 

Low-level  Utility  Layer 

-Database  access.  Magnetic  field,  HdfS  and  Boost 


In  addition  to  this  User’s  Guide,  there  are  several  other  files  of  information  provided  in  this 
distribution.  The  ‘Readme_CmdLineAe9Ap9’  file  provides  a  complete  list  of  various  database 
and  supporting  files  used  in  the  model.  Several  annotated  samples  of  command-line  input  files 
are  also  supplied; 


Ae9Ap9CmdlineInputSample  VI  0 . txt 
Ae9Ap9CmdlineOrbitSample.txt 
Ae8Ap8CrresCmdlineInputSample  VI  0 . txt 
CammiceCmdlinelnputSample  VI  0 . txt 

Additional  subdirectories  contain  several  test  files  (both  input  and  output)  for  verifying  proper 
model  installation  and  operation. 
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Model  Installation 

Version  1.00.003  of  the  AE9/AP9  Radiation  Environment  model  is  distributed  as  a  zipfile, 
‘Ae9Ap9_version_l .  00 . 003  .  zip’,  containing  Windows  release-mode  binaries  and  libraries, 
model  databases,  sample  input  and  output  fdes  and  supporting  documentation  fdes.  A  separate 
source  distribution  may  also  be  provided,  upon  request,  for  generating  Windows  debug-mode 
binaries,  or  for  building  the  binaries  on  Einux  platforms. 

For  a  Windows  installation,  simply  unzip  the  distribution  file  in  the  desired  directory  location. 
The  directory  structure  will  be  as  shown  below: 


For  a  Einux -based  installation,  unzip  the  source  distribution  file  in  the  desired  location,  then  refer 
to  the  detailed  instructions  in  the  ‘Build_instructions_for_AE9AP9.pdf’  file  in  the 
‘Ae9Ap9/documents’  directory. 

Installation  Testing 

Open  a  command  line  window,  navigate  to  the  directory  containing  the  binary  executables  (ie 
Ae9Ap9/bin/win32),  enter  the  command: 

CmdLineAe9Ap9  -i  . . / . . /consoleTests/short . txt 

The  resulting  output  files  will  be  written  in  this  same  directory.  Verify  that  the  number  of  files 
generated,  and  respective  file  contents  match  that  of  the  “shortoutput”-prefixed  files  located  in 
the  ‘ . .  / . .  /consoieTests/expectedTestoutputs  ’  directory.  Other  test  input  files  are  also 
available  in  this  ‘consoleTests’  directory,  and  their  corresponding  output  files  in  the 

‘expectedTestOutputs’  subdirectory. 

Much  more  information  regarding  the  CmdLineAe9Ap9  program  is  provided  in  the  next  section 
of  this  document. 
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To  start  the  GUI  program,  enter  the  command  (or  double-click  the  icon  for): 

testAe9Ap9Gui . exe 

A  detailed  description  of  the  GUI  program  follows  in  a  later  section  of  this  document. 


Command-Line  Program 

The  CmdLineAe9Ap9  program  is  a  lightweight  client  application  for  running  the  ‘AE9/AP9’  and 
‘Plasma’  models  at  time-tagged  orbital  positions.  The  requested  model  calculation  results  are 
written  to  comma-separated  value  (CSV)  format  text  files.  Other  ‘legacy’  radiation  belt  models, 
‘AE8’,  ‘AP8’,  ‘CRRESELE’,  ‘CRRESPRO’  and  ‘CAMMICE/MICS’,  are  also  available  within  this 
same  application. 

The  command-line  utility  takes  input  settings  from  an  external  file,  which  is  passed  to  it  using 
the  input  parameter  ‘-i  <filename>\  This  feature  permits  the  CmdLineAe9Ap9  program  to  be 
used  in  “batch”  mode  or  within  a  script,  and/or  distributing  large  modeling  tasks  across  multiple 
processors  and  servers.  Very  long  model  runs  can  easily  be  broken  up  by  time  or  species,  and 
the  results  merged  using  user-supplied  post-processing  scripts. 

The  format  of  the  input  file  used  to  drive  the  CmdLineAe9Ap9  program,  as  well  as  the  detailed 
model  settings  specified  within  it,  are  described  below.  A  working  sample  input  file, 
‘Ae9Ap9CmdLinelnputSample_vi_0  .  txt'  is  provided  in  the  ‘Ae9Ap9/bin/win32’  directory. 
This  annotated  sample  file  contains  complete  descriptions  of  all  available  input  parameters  to  the 
model  and  all  of  the  allowed  values  for  each. 

Input  File  Construction 

The  basic  format  of  the  input  file  is  ‘keyword/value’  pairs  on  each  line:  the  parameter  keyword 
name,  followed  by  a  colon  and  then  the  value  or  values  for  the  parameter.  Keywords  and  string 
values  are  not  case-sensitive.  Lines  beginning  with  a  ‘#’  symbol  are  treated  as  comments,  and 
are  therefore  ignored  by  the  program. 

CmdLineAe9Ap9  input  file  settings  can  be  logically  grouped  into  the  following  categories: 

Basic  Model  Inputs  -  core  model  parameters,  required  for  any  model  run 

Aggregation  Inputs  -  optional  settings  for  combining  complex  output  results 

Dose  Calculation  Inputs  -  optional  settings  to  drive  the  ShieldDose2  dose  calculations 
Orbit  Propagator  Inputs  -  optional  settings  for  generating  orbit  ephemeris 

Input  file  settings  for  each  of  these  categories  are  described  in  the  following  tables.  Descriptions 
of  the  parameters  used  for  the  legacy  models  may  be  found  in  the  Appendices. 
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Basic  Model  Inputs 


Approved  for  public  release;  distribution  is  unlimited. 

6 


FluxType  IPtDiff,  2PtDifP,  Integral  Required  none  Type  of  flux  to  be  computed. 


Approved  for  public  release;  distribution  is  unlimited. 


MagfieldDB  <paf/7>/igrfDB.h5  Required  none  Magnetic  field  model's  database  file,  including  path 
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Details  about  the  Flux  Data  Modes 

The  ‘FluxOut’,  and  associated  parameters,  is  used  specify  the  various  types  of  flux  data  to  be  returned  by  the  model.  The  ‘mean’  and 
‘percentile’  modes  capture  the  statistical  behavior  of  the  data  upon  which  the  model  was  built.  The  ‘perturbed’  mode  adds  the 
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Aggregation  Inputs 

Model  aggregation  values  are  available  when  the  ‘FluxOut/perturbed,###’  and/or  ‘FluxOut/montecarlo,###’  parameters  are  specified, 
but  are  statistically  meaningful  only  when  at  least  five  scenarios  are  used.  Each  of  these  parameters  may  appear  multiple  times  in 
order  to  specify  the  desired  aggregate  output  files.  ‘MonteCarlo’  aggregations  are  not  applicable  to  ‘Plasma’  model  outputs. 
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DoseDepthU  millimeters  Optional  millimeters  Units  of  Aluminum  shielding  thickness  depth 

mils 
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constant. 


Orbiter  Propagator  Inputs 

When  the  appropriate  set  of  these  orbit  parameters  is  specified,  the  generated  ephemeris  information  is  written  to  the  file  specified  by 
the  ‘OrbitFile’  parameter  (in  the  Basic  Model  Inputs  group),  replacing  the  ephemeris  file  if  it  already  exists.  However,  be  aware 
that  the  ephemeris  time  and  position  and  information  (supplied  or  generated)  is  always  included  in  all  model  output  files. 
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OrbElmTim  Date/time  Conditionally  none  Time,  in  Modified  Julian  day*  form,  associated  with  the 

Required*  specified  orbital  element  values 
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OrbArgPer  0  -  360  (degrees)  'mean'  none  Argument  of  perigee  (degrees) 


OrblstDer  -10- +10  'mean'  none  First  derivative  of  mean  motion  (rev/day^) 
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OrbGeoLon  0  -  360  (degrees)  rgeosync'  none  Geographic  longitude  (deg)  at  orbital  element  time 


Two-Line  Element  Files 

Two-Line  Element  (TEE)  is  a  standard  NORAD  data  format  used  to  convey  sets  of  orbital 
element  values  that  describe  the  orbital  motion  of  Earth-orbiting  satellites.  Current  and  archived 
TEE  data  for  many  satellites  may  be  obtained  from  various  online  sources,  such  as 
http;//www.celestrak.com. 

The  orbit  propagator  routines,  such  as  ‘SGP4’  and  ‘SatEph’,  can  use  TEE  files  that  contain 
multiple  entries  of  TEE  (in  chronological  order)  for  a  single  satellite.  The  ‘SatEph’  routines 
perform  interpolation  between  adjacent  TEE  entries  for  smooth  ephemeris  results. 

The  standard  NORAD  format  for  the  Two-Eine  Elements  is  shown  in  the  table  below: 


TIE  Line  1 

TLE  Line  2 

Column 

Description 

Column 

Description 

01 

Line  Number  of  Element  Data 

01 

Line  Number  of  Element  Data 

03-07 

Satellite  Number 

03-07 

Satellite  Number 

08 

Classification  (LI=Llnclassified) 

09-16 

Inclination  [Degrees] 

10-11 

International  Designator  (Last  two  digits  of 
launch  year) 

18-25 

Right  Ascension  of  the  Ascending  Node 
[Degrees] 

12-14 

International  Designator  (Launch  number  of 
the  year) 

27-33 

Eccentricity  (decimal  point  assumed) 

15-17 

International  Designator  (Piece  of  the 
launch) 

35-42 

Argument  of  Perigee  [Degrees] 

19-20 

Epoch  Year  (Last  two  digits  of  year) 

44-51 

Mean  Anomaly  [Degrees] 

21-32 

Epoch  (Day  of  the  year  and  fractional 
portion  of  the  day) 

53-63 

Mean  Motion  [Revs  per  day] 

34-43 

First  Time  Derivative  of  the  Mean  Motion 

64-68 

Revolution  number  at  epoch  [Revs] 

45-52 

Second  Time  Derivative  of  Mean  Motion 
(decimal  point  assumed) 

69 

Checksum  (Modulo  10) 

54-61 

BSTAR  drag  term  (decimal  point  assumed) 

63 

Ephemeris  type 

65-68 

Element  number 

69 

Checksum  (Modulo  10) 

Example  Two-Eine  Element  set  (32765  =  C/NOES  satellite): 

1  32765U  08017A  11150.09749074  +.00010799  +00000-0  +47888-3  0  0797 

2  32765  013.0015  105.8044  0295409  031.4522  330.3172  14.8643027916917 

Some  potentially  helpful  online  resources  for  understanding  the  orbital  element  definitions: 

http : / / WWW . braeunig .us/ space/ orbmech . htm 
http : / / WWW . amsat . org/ amsat/keps/kepmodel . html 

http : / /marine . rutgers . edu/mrs/ education/ class /paul/ orbits . html 
http : / /en . wikipedia . org/ wiki /Orbital  elements 
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Orbit  Ephemeris  File  Description 

The  ephemeris  file,  required  for  performing  the  model  ealeulations,  can  be  generated  by  one  of 
the  available  orbit  propagators,  or  can  be  supplied  by  the  user  (but  must  be  in  the  expected 
format).  The  user-supplied  (input)  or  generated  (output)  ephemeris  file  name  is  specified  with 
the  required  ‘OrbitFile’  parameter. 

The  comma-separated  value  (CVS)-formatted  ephemeris  file  may  contain  any  number  of  header 
lines  (comments),  designed  with  a  ‘#’  in  the  first  column.  The  data  values  are  expected  in  four 
columns:  date/time  (in  Modified  Julian  day+fraction  form,  see  Appendix  C),  and  three 
coordinates  of  one  of  the  supported  coordinate  systems  (in  the  specified  order  and  appropriate 
units).  The  coordinate  system  of  the  user-supplied  ephemeris  file  is  specified  by  the  ‘CoordSys’ 
parameter. 

Any  ephemeris  files  generated  by  the  orbit  propagator  during  the  model  runs  will  always  use  the 
GEI  coordinate  system  and  units.  The  ephemeris  information,  from  either  source,  is  included 
the  model  output  files. 


Model  Output  Files 

The  input  file  specifications  define  the  types  of  model  calculations  to  be  performed,  and  the 
corresponding  output  file  or  files  are  generated.  The  different  types  of  output  files  are 
distinguished  by  the  type  of  data,  its  calculation  mode,  and  aggregation/division. 

The  names  of  the  model  output  files  are  constructed  from  the  required  ‘OutFile’  and  ‘FluxOut’ 
parameter  values,  other  optional  model  output  parameter  values,  and  any  model  output 
aggregation  parameter  specifications.  The  basic  output  file  name  assembly  scheme  is  below. 
This  scheme  ensures  unique  output  file  names  that  provide  descriptive  information  about  its 
contents. 


Prefix 

Data  Mode 
based  on 
<*Out>  value 

Data  Type 
based  on 
<*Out>  keyword 

S  cenario/  Aggregation 
based  on 

<*Agg*>  keyword 

Suffix 

<OutFile> 

mean 

_flux 

f luence 

dose 

totaldose 

(-n/a-  for  mean) 

.  txt 

pctile 

(percentile,  in  <FluxOut>  value) 

pert 

me 

(scenario  identification  #) 

agg  mean 
agg  median 
agg  pctile  ## 

Each  model  output  file  contains  several  header  lines  (comments,  defined  by  ‘#’  in  first  column) 
that  identify  the  model,  its  parameters,  type  of  output  values,  and  other  pertinent  information  (but 
not  necessarily  the  complete  set  of  model  parameters).  The  last  header  line  specifies  the  data 
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column  labels  and  units.  Each  (CSV-format)  data  line  contains  the  date/time  (as  Modified  Julian 
day+fraction,  see  Appendix  C),  the  GEI  Cartesian  coordinates  (in  Re),  followed  by  one  or  more 
data  values,  as  appropriate  for  the  fde’s  data  type/mode/aggregation. 


Tandem  AE9/AP9  and  Plasma  Model  Calculations 

The  ‘AE9/AP9’  model  and  ‘Plasma’  model  (for  the  ‘electron’  and  ‘H+’  species)  maybe  used  in 
tandem  to  provide  results  over  a  broader  energy  range.  However,  because  these  two  models 
were  developed  independently,  the  results  where  their  energy  ranges  overlap  will  not  always 
match.  When  used  together,  it  is  recommend  that  the  ‘Plasma’  model  energy  levels  specified  be 
less  than  0.04MeV  for  electrons,  and  less  than  O.lMeV  for  protons. 

The  ‘Plasma’  model  differential  flux  values  returned  may  be  used  as-is.  However,  to  obtain  true 
integral  flux  results,  information  for  the  energy  levels  that  are  above  the  ‘Plasma’  model  energy 
limits  needs  to  be  included.  Pseudo-integral  flux  Plasma  model  runs  may  be  performed  at  the 
desired  energies,  using  ‘FluxType’=‘2PtDiff’,  with  the  ‘Energies2’  list  values  all  set  to  0.04MeV 
for  electrons  or  O.lMeV  for  protons.  Integral  flux  ‘AE9/AP9’  model  runs  are  required  at 
0.04MeV  (and  other  energies,  if  desired)  for  electrons  and  O.lMeV  (and  others)  for  protons, 
using  the  same  ephemeris  information  as  the  Plasma  runs.  When  all  runs  have  been  executed, 
use  the  ‘  integralPlasma .  exe’  command-line  application  utility  to  perform  a  post-processing 
adjustment  of  the  Plasma  results.  This  rewrites  the  Plasma  integral  output  files,  revising  the 
‘2PtDiff’  values  to  be  ‘Integral’  values,  incorporating  the  respective  ‘AE9/AP9’  integral  results  at 
their  lowest  energies.  More  information  about  this  utility  program  may  be  found  in  the 
accompanying  ‘intPlasma  Readme .  txt’  file.  Eor  user  convenience,  this  entire  post-processing 
adjustment  operation  is  performed  automatically  within  the  GUI  program  for  these  types  of 
model  calculations. 


Model  Run  Performance  Tuning 

When  executing  the  model  program  on  systems  with  limited  amounts  of  free  memory,  the 
overall  performance  may  be  improved  by  specifying  an  additional  parameter  in  the  model  run 
input  file.  The  (optional)  tuning  parameter  ‘PtsPerCalf  (default  value  =  240)  defines  the  number 
of  orbital  positions  being  processed  during  each  call  to  the  lower-level  model  routines.  The  size 
of  this  processing  ‘chunk’  directly  relates  to  the  amount  of  memory  needed  beyond  the  model 
overhead.  Specifying  a  lower  value,  such  as  120,  should  improve  performance  times  on  limited- 
memory  systems.  Eower  values  will  also  increase  the  frequency  of  progress  updates. 

No  parallel  processing  capabilities  are  currently  implemented  in  the  model  program.  Separate 
model  runs  may  executed  simultaneously,  provided  an  adequate  amount  of  memory  is  available 
to  support  this.  See  the  ‘Epoch’  parameter  (in  Basic  Model  Inputs)  for  related  information. 
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Graphical  User  Interface  Program 

The  GUI  program  provides  a  simple  graphieal  user  interface  front-end  for  performing  model 
runs  with  the  CmdLineA9Ap9  program.  Based  on  the  selections  and  specifications  made  in  the 
user  interface,  the  appropriate  parameter  input  files  are  generated  and  executed.  Basic  2-D  plots 
of  the  calculated  model  results  may  be  produced. 

The  GUI  program  writes  files  to  a  subdirectory  (default  name  =  “Run”)  of  the  program 
installation  location.  This  directory  is  created  if  it  does  not  exist;  the  user  may  choose  another 
name  and/or  location  for  this  directory.  For  each  model  run,  the  necessary  input  files  are  written 
in  this  directory,  and  used  with  the  command  line  program.  The  generated  ephemeris  files, 
model  run  output  files,  and  plot  data  files  are  also  written  to  this  same  directory,  with  a  user- 
supplied  'RunName'  prefix  in  their  filenames. 

The  ‘Ae9Ap9GuiDBConf  ig .  txt’  configuration  file  is  used  to  identify  the  names  and  locations  of 
the  various  model  data  base  files;  these  are  referenced  in  the  model  run  input  files  generated  by 
the  GUI  program.  Use  extreme  caution  when  modifying  this  database  configuration  file,  as 
changes  made  here  will  alter  model  results  and/or  cause  model  run  failures.  The  previously- 
discussed  model  performance  tuning  parameter,  ‘PtsPerCalf,  may  also  be  specified  in  this 
configuration  file. 

The  GUI  controls  are  divided  into  three  tabbed  pages,  labeled  ^Satellite',  ^ Model'  and  ‘Plot’. 

The  usage  and  available  features  on  each  of  these  pages  are  described  in  the  following  sections. 
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Satellite  Tab 

This  page  collects  all  necessary  information  for  defining  the  times  and  orbital  positions  at  which 
the  radiation  environment  model  values  are  to  be  calculated,  usually  along  a  satellite  orbital  path 
for  a  specific  time  segment  and  increment. 


The  "Satellite  Name'  is  only  required  when  specifying  custom  orbital  elements,  and  is  used  as 
part  of  the  filename  of  the  generated  ephemeris  file,  in  the  form:  ‘ephem_<SatiVame>.  dat’.  If 
not  supplied,  the  default  name  of  ‘sat’  will  be  used. 

For  the  orbit  specification  "Input  type' ,  select  "Ephemeris  (Time+Position)'  to  use  an  existing 
ephemeris  file  (CSV-formatted)  containing  a  list  of  times  and  positions,  in  one  of  the  supported 
coordinate  system,  as  specified  by  the  drop-down  box  to  the  right.  Note  that  the  times  are 
expected  to  be  in  Modified  Julian  date  plus  fractional  day  form,  and  the  coordinate  values  that 
follow  are  in  the  listed  order,  and  in  the  specified  units.  See  the  “Supported  Coordinate  Systems” 
table,  on  page  10. 
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Model  calculations  at  a  grid  of  positions  for  a  particular  date  and  time  may  be  also  performed 
using  the  'Ephemeris'  input  type.  However,  these  results  at  a  single  fixed  time  are  unable  to  be 
plotted  in  the  user  interface  ‘Plot’  page,  due  to  its  limited  capabilities. 

The  orbital  path  may  also  be  defined  by  specifying  a  file  containing  NORAD-standard  ‘Two- 
Line  Elements’  (TLE)  entries,  as  previously  discussed  in  the  CmdLineAe9Ap9  program 
description  section.  The  TLE  file  can  contain  multiple  entries,  but  for  a  single  vehicle  only. 

The  use  of  the  ‘Mean  Element  Entry’  or  ‘Solar  Element  Entry’  selection  permits  their  respective 
sets  of  orbital  element  values  to  be  specified  manually.  Please  note  the  units  for  each  of  the 
parameters,  in  particular  for  ‘Mean  Motion’ .  The  ‘Element  Time’  value  associated  with  these 
orbital  element  values  is  also  required. 

An  ephemeris  file  is  generated  (during  the  model  run)  from  the  specified  orbital  element  inputs, 
using  one  of  three  orbit  propagators,  whose  availability  depends  on  the  ‘Input  Type’  selection. 
The  generated  ephemeris  positions  are  always  in  the  GEI  (ECI)  coordinate  system.  The  available 
orbit  propagators  are  briefly  described  below. 

•  The  'Lokangle'  (or  'SatEph')  propagator,  developed  and  used  by  researchers  at  AFRL  for  several  decades.  It 
accounts  for  secular  and  periodic  perturbations,  gravitational  effects,  and  atmospheric  drag.  This 
propagator  performs  interpolation  of  the  orbital  elements  between  adjacent  TLE  entries. 

•  The  'SGP4'  (Simplified  General  Perturbations)  propagator  (sometimes  called  SPACETRACK)  considers 
secular  and  periodic  variations  due  to  Earth  oblateness,  solar  and  lunar  gravitational  effects,  gravitational 
resonance  effects,  and  orbital  decay  using  a  drag  model.  It  uses  the  latest  TLE  entry  for  the  given  time, 
and  may  exhibit  a  slight  discontinuity  in  the  ephemeris  position  at  the  time  of  next  TLE  entry. 

•  The  'Kepler'  propagator  is  very  basic  orbit  propagator,  without  applying  any  perturbations,  except  for  'J2' 
effects  if  selected.  The  'J2'  perturbation  accounts  for  secular  variations  in  the  orbit  due  to  oblateness  of 
the  Earth.  The  minimal/no  perturbations  makes  the  Kepler  propagator  ideal  for  the  generation  of 
extremely  long-duration  ephemeris  information  with  stable  orbit  characteristics.  By  neglecting  higher- 
order  physics,  this  propagator  simulates  the  effects  of  station  keeping  maneuvers. 

Both  the  'SGP4'  and  'Kepler'  propagators  are  'forward-generating'  only.  That  is,  they  are  unable  to  compute 
ephemeris  at  times  prior  to  the  specified  'Element  Time',  or  prior  to  the  first  time  value  in  the  supplied  TLE  file. 

The  time  limits  of  the  ephemeris  file  to  be  generated  are  speeified  by  the  ‘Start  Time’  and  ‘End 
Time’  entries,  with  an  assoeiated  time  increment.  Please  keep  in  mind  that  a  small  ‘Time  Step’ 
value  will  result  in  more  time  values  at  which  the  model  values  are  being  calculated.  Model  runs 
for  long  time  periods  with  small  time  steps  could  potentially  require  many  hours,  days  or  weeks 
to  complete,  depending  on  your  computer  system  performance.  The  recommended  time  step 
values  for  adequate  model  resolution,  based  on  the  general  orbit  type,  are:  LEO:  10  seconds; 
MEO:  300  seconds;  HEO:  60  seconds;  GEO:  3600  seconds.  The  optimal  time  step  size  will 
depend  on  the  exact  characteristics  of  the  satellite  orbit  being  used. 
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For  TLE  input  files,  the  'AutofilF  button  is  available  -  when  pressed,  the  TLE  file  is  seanned,  and 
the  'Start  Time'  is  set  to  rnateh  to  the  first  element  entry  time,  and  the  'End  Time'  is  set  to  be  the 
last  element  entry  time  plus  one  day.  The  filename  of  the  generated  ephemeris  file  will  be  in  the 
form:  ' e.'p'n.em_<TLE_input_f i le> .  dat’. 

When  all  seleetions  and  speeifieations  have  been  made,  press  the  'Set'  button.  The  various 
inputs  are  eheeked,  ensuring  valid  element  values  and  time  entries.  If  applieable,  the  input  file  is 
also  seanned,  eonfirming  the  expeeted  format  and  that  its  values  are  within  their  respeetive 
aeeeptable  ranges.  An  informative  dialog  box  will  be  displayed  if  any  problems  are  deteeted. 
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Model  Tab 

This  page  collects  all  user-specified  parameters  required  for  calculating  the  various  model  values 
at  the  defined  ephemeris  positions.  Each  set  of  model  run  input  and  output  files  will  be  written 
in  the  specified  "Run'  directory,  with  their  file  names  containing  the  prefix  specified  in  the 
"RunName'  entry. 


Five  models  are  available  from  the  "Model'  drop-down  box  -  ‘AE9/AP9’,  ‘Plasma’,  and  three 
“legacy”  models:  ‘AE8/AP8’,  ‘CRRES  ELE/PRO’  and  ‘CAMMICE/MICS’.  Depending  on  which 
model  is  selected,  the  appropriate  parameter  selections  are  shown  in  the  GUI  window. 


For  the  ‘AE9/AP9’,  ‘AE8/AP8’  and  ‘CRRES  ELE/PRO’  models,  dose  calculations  may  also  be 
performed  using  the  calculated  particle  fiux  and  fiuence  results.  This  feature  is  activated  by 
checking  the  "Compute  Dose'  checkbox,  which  enables  the  selection  of  the  “ShieldDose2” 
model  parameters,  and  also  automatically  selects  all  energy  levels  of  both  electrons  and  protons. 
The  "Dose  Interval'  value  specifies  the  frequency  (in  ephemeris  data  time)  at  which  the  dose 
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calculations  are  performed.  A  value  of  “0.0”  means  the  ealeulations  are  performed  at  every 
timestep,  whieh  may  significantly  lengthen  the  overall  model  exeeution  time.  A  value  of  “0.25” 
(days)  means  the  ealeulations  are  performed  on  the  aggregation  of  flux  values  for  the  preceding  6 
hours-worth  of  ephemeris  positions.  Additional  information  about  the  other  “ShieldDose2” 
model  parameters  may  be  found  in  the  previous  Command-Line  Program/Dose  Calculation 
Inputs  section  (page  14)  of  this  doeument,  and  [Seltzer,  1994]. 

The  values  in  the  'Shield Depths'  list  may  be  displayed  in  units  of  'g/cm  'mm'  or  'mils'.  Using 
the  drop-down  box  to  seleet  a  different  unit  will  automatieally  convert  the  existing  entry  values 
to  the  new  units. 

The  values  eomprising  the  'Shield  Depths'  list  may  also  be  eustomized.  Double-eliek  on  an  entry 
to  edit  its  value  (or  alternatively,  use  Shift-HCtrl-l-cliek).  When  the  editing  of  an  entry  is 
eomplete,  its  position  in  the  list  will  automatieally  be  adjusted  to  maintain  inereasing  numerieal 
order.  Entering  “0”  or  blank  will  delete  the  entry.  New  entries  may  be  added  to  the  list  by 
selecting  the  speeial  '[-Add-]'  entry  at  the  bottom  of  the  list.  The  list’s  pop-up  “tooltip” 
information  shows  the  expeeted  range  of  valid  values,  as  well  as  these  editing  instruetions. 

These  eustomized  list  values  may  be  saved  to  a  file  by  pressing  ‘Shift’  when  elieking  on  a  list 
entry.  A  saved  list  of  values  may  be  reloaded  by  pressing  ‘Ctrl’  when  elieking  on  a  list  entry. 
Only  valid  list  entries  from  appropriate  list  files  will  be  loaded.  Appropriate  error,  warning  or 
informational  dialogs  will  be  displayed  as  needed. 


AE9/AP9-specific  notes: 

The  Electron  and  Proton  energy  lists  show  two  distinet  sets  of  values  within  eaeh  list. 
Those  energy  values  with  five  digits  to  the  right  of  the  deeimal  point  are  calculated  using 
the  SPM  ‘Plasma’  model  for  ‘eleetrons’  and/or  ‘H-H’ (protons).  Those  energy  values  with 
only  two  digits  are  calculated  with  the  AE9/AP9  model.  “Monte  Carlo”-type  ealeulations 
will  not  be  available  if  any  of  the  ‘Plasma’  energy  values  are  seleeted.  These  energies  may 
be  removed  from  the  list  toggling  the  provided  checkbox. 

The  calculation  of  Integral  flux  values  of  the  ‘plasma’  energies  will  automatically  invoke  a 
calculation  of  the  integral  flux  values  of  the  AE9/AP9  at  their  respeetive  lowest  energy 
levels,  if  not  already  seleeted.  The  results  produeed  for  the  plasma  energy  levels  will  be 
adjusted  to  ineorporate  the  results  of  these  lowest  energy  AE9/AP9  energies.  This  post¬ 
processing  adjustment  of  the  plasma  results  is  performed  automatically  within  the 
operation  of  the  GUI.  For  manually-performed  model  runs,  the  ‘integralPlasma’  utility 
may  be  used  to  perform  this  post-proeessing  adjustment,  provided  that  the  speeifie  set  of 
requirements  of  the  associated  model  runs  are  met. 


The  energy  lists  for  the  ‘AE9/AP9’  and  ‘Plasma’  models  only  may  be  customized  in  the  same 
manner  as  that  of  the  'Shield  Depths'  list.  The  energy  list  values  used  with  the  legacy  models 
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cannot  be  changed.  The  ‘CAMMICE/MICS’  legacy  model  always  calculates  results  for  all  of  its 
pre-defmed  energy  bins. 

If  one  of  the  legacy  ‘AE8/AP8’  or  ‘CRRES  ELE/PRO’  models  is  selected,  additional  parameters  are 
available  via  the  ‘Advanced’  button.  A  warning  is  displayed:  un-physical  results  may  be 
produced  if  the  default  ‘Advanced’  settings  are  altered.  After  acknowledging  this  warning,  an 
extra  dialog  box  is  shown,  containing  two  checkboxes.  The  “Use  Native  Epoch”  option  is 
checked  by  default,  and  imposes  the  use  of  model-specific  year  values  (rather  than  the  year 
specified  by  the  satellite  ephemeris)  for  the  magnetic  field  model  when  performing  the  flux 
calculations  for  these  legacy  models.  The  “Translate  SAA”  option,  unchecked  by  default,  can  be 
used  to  shift  the  SAA  from  its  ‘native  epoch’  year  location  to  that  for  the  current  year  specified 
in  the  satellite  ephemeris.  See  [Heynderickx  et  al,  1996]  for  more  details. 

When  all  model  parameters  and  settings  have  been  selected,  press  the  'Run'  button.  The  various 
model  parameter  inputs  are  verified  to  contain  proper  and/or  compatible  settings.  An 
informative  error  dialog  is  displayed  if  problems  are  detected.  If  the  'RunName'  specification 
has  been  used  before,  a  dialog  box  will  ask  if  the  previously  generated  files  may  be  overwritten. 
When  the  various  selections  have  all  been  verified,  a  set  of  input  files  are  generated,  named  in 
the  form:  ' <RunDir>/ <RunName> .  <Mode J >.  CLinput .  txt’.  These  input  files  are  supplied  to  the 
Command-Line  program  for  the  model  execution.  Model  runs  that  require  multiple  portions  to 
be  executed  (ie.  Electrons  and  Protons),  are  done  in  a  serial  manner  (no  parallel  execution  is 
available  at  this  time).  Any  required  ephemeris  file  generation  will  be  performed  during  the  first 
portion,  and  the  resulting  file  will  be  used  as  input  for  subsequent  portions.  If  an  error  occurs 
during  one  of  the  model  run  portions,  any  remaining  portions  will  not  be  run,  and  the  model  run 
files  associated  with  'RunName'  will  be  marked  as  “incomplete”.  An  error  dialog  will  notify  the 
user  if  this  occurs. 

During  the  execution  of  the  necessary  model  runs,  the  'Run'  button  will  show  '-busy-' ,  and  the 
run  status  will  be  shown  in  the  '%  Complete'  progress  bar.  The  update  rate  and  frequency  of  this 
progress  bar  will  vary,  depending  on  the  number  of  ephemeris  positions  being  used,  the  model 
and  species  selected,  and  the  types  of  calculations  being  performed.  While  “busy”,  the  various 
satellite  and  model  GUI  selections  are  able  to  be  viewed,  but  no  changes  are  permitted.  When 
the  model  runs  have  successfully  completed,  the  button  is  changed  back  to  showing  ‘Run’.  The 
generated  model  output  files  are  named  in  the  form: 

'  <RunDir>/  <RunName> .  <Model> .  CLoutput_<type>.  txt’.  The  prc-dcfined  ‘  <Model>'  names 
are  shown  in  the  next  section.  The  various  permutations  for  '  <type>'  are  shown  in  the  previous 
Command-Line  Program/Model  Output  Files  section. 


Approved  for  public  release;  distribution  is  unlimited. 
26 


Plot  Tab 

This  page  provides  a  method  for  producing  basic  2-D  plots  of  the  model  calculation  results. 


For  the  specified  "Directory’’  location,  all  available  ‘RunName’  model  runs  are  shown  in  the 
drop-down  list.  These  can  be  from  this  current  or  any  previous  GUI  program  session.  Manually- 
configured  and  -executed  model  runs  may  also  be  selected,  provided  that  the  expected  input  and 
output  file-naming  form  has  been  used; 


Input  file  —  ‘"<RunName> .  <Model> .  CLinput .  txt”, 
and  containing  ‘OutFile’  parameter  =  "‘’<RunName>.  <Mode J>.CLoutput .  txt”. 


Where  <Model>  is  one  of:  ‘AE9’,  ‘AP9’,  ‘PLASMA_E’,  ‘PLASMA_0’,  ‘PLASMA_H’,  or 
‘PLASMA_HE’,  and/or; 

-  for  AE9/Ap9/SPM  “tandem”  runs  ;  ‘PLASMAelec’  and  ‘PLASMAprot’ 

-for  legacy  models:  ‘AE8’,  ‘AP8’,  ‘CRRESELE’,  ‘CRRESPRO’  or ‘CAMMICE’. 
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Based  on  the  input  and  output  files  of  the  seleeted  'RunName',  the  model  name  and  flux  type  are 
identified,  and  the  lists  for  energy  levels  and  shield  depths  used  are  appropriately  populated. 
Other  pertinent  information,  such  as  scenario  collections,  pitch  angles  and/or  species  are  also 
shown.  Additional  details  of  the  full  set  of  model  parameters  are  always  available  from  the 
model  run  input  files. 

If  the  selected  RunName'  has  been  marked  as  “incomplete”,  a  warning  dialog  is  displayed. 
Attempts  to  plot  from  this  may  show  incorrect  results  and/or  cause  program  instability. 

The  selection  methods  for  the  desired  energy  levels  or  shield  depth  values  will  depend  on  the 
type  of  plot  desired:  versus  Rime',  'Energy'  or  'Thickness' .  The  model  run  parameters  may  also 
dictate  additional  selections  are  needed,  such  as  species,  or  scenario  numbers  and/or  percentiles. 

For  plots  of  values  versus  'Energy'  or  'Thickness' ,  two  time-slice  specification  methods  are 
available.  The  'Time  Selection'  slider  allows  a  specific  time  value  within  the  dataset  to  be 
selected.  Alternatively,  when  the  'Num  Times'  spinbox  is  changed  from  zero,  this  specifies  the 
number  of  evenly-spaced  time  slices  to  plot,  the  first  one  always  at  time  “t=0”  of  the  time  period. 

Press  the  'Plot'  button  when  selections  are  complete.  An  informative  error  dialog  is  displayed  if 
additional  selections  are  required.  The  plot  is  displayed  in  a  new  window;  the  GUI  will  remain 
frozen  until  this  plot  window  is  closed.  However,  if  the  selected  model  results  are  all  zeros,  no 
plot  will  be  produced  and  a  notice  is  displayed. 

Based  on  the  selections  made,  one  or  more  sets  of  data  values  are  plotted,  each  using  a  different 
color  and/or  dot/dash  pattern.  The  key  below  identifies  each  of  these  lines.  Dose  values  are 
plotted  based  on  their  'Dose  Interval'  specification,  and  so  these  graphs  versus  time  may  appear 
as  steps  rather  than  curves  if  a  non-zero  interval  is  used. 

For  each  plot  produced,  a  CSV-formatted  file  of  the  data  plotted  is  written  in  the  same  directory. 
These  files  are  suitable  for  use  by  other  plotting  programs.  The  file-naming  form  is: 

'  <RunName>_^lot_<###>  .tKt' ,  where  '###'  is  simply  the  number  of  the  plot  generated  during 
the  current  GUI  program  session.  Parameter  labels  for  each  data  column  are  included  in  these 
plot  data  files,  but  do  not  provide  model  run  parameters.  These  details  are  always  available  in 
the  associated  ' RunName' -pveTix  model  input  files. 


Example  GUI-based  Model  Runs 

Several  examples  of  using  the  GUI  to  perform  model  runs  and  produce  basic  plots  are  shown  in 
the  series  of  screenshots  below. 
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Example  1:  MeanSample  Model  Tab;  Plot  Tab; 

Satellite  Tab; 

-Enter  ‘MeanSample’  for  Run  Name  At  the  eonelusion  of  the  model  run,  switeh 

-Select  ‘Ephemeris’  -Select  a  directory  for  files  to  the  ‘Plot’  tab;  the  Run  Name  will 

-Enter  ‘short  leo.csv’  for  Input  File  -Check  ‘Compute  Dose’  checkbox  automatically  be  set  to  the  ‘MeanSample’ 
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MeanSample,  Continued  (Plot  Tab)  -^Flux  or  Fluence  vs  Time 
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-Check  ‘Mean’  and  ‘95*’  percentiles 
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-Enter  ‘PMSample’  for  Run  Name 

-Seleet  ‘Perturbed  Mean’,  with  #Runs=15  -Many  types  of  plots  are  available 
-Uneheck  ‘Include  Plasma  Energy  Eevels’  'Selections  can  be  determined  from  each 
-Check  ‘Compute  Dose’  checkbox  ^  labels  and  legends 


References: 


Bhavnani,  K.H.,  and  R.P.  Vancour,  “Coordinate  systems  for  spaee  and  geophysieal 
applieations,”  PL-TR-9 1-2296,  Phillips  Laboratory,  Hanseom  AFB,  MA, 
rhttp://www.dtic.mil/dtie/tr/fulltext/u2/a247550.pdf1,  11  Dec.  1991. 

Ginet,  G.P.,  T.P.  O’Brien,  S.L.  Huston,  W.R.  Johnston,  T.B.  Guild,  R.  Friedel,  C.D.  Lindstrom, 
C.J.  Roth,  P.  Whelan,  R.A.  Quinn,  D.  Madden,  S.  Morley,  and  Yi-Jiun  Su,  “AE9,  AP9  and  SPM; 
New  Models  for  Specifying  the  Trapped  Energetic  Particle  and  Space  Plasma  Environment,” 
Space  Science  Reviews,  rhttp://dx.doi.org/10.1007/sll214-013-9964-v1,  March  2013. 

Seltzer,  Stephen  M.,  “Updated  Calculations  for  Routine  Space-Shielding  Radiation  Dose 
Estimates:  SHlELDOSE-2,”  National  Institute  of  Standards  and  Technology  Publication  NISTIR 
5477,  1994. 

Heynderickx,  D.,  J.  Eemaire,  E.J.  Daly,  and  H.D.R.  Evans,  “Calculating  Eow-Altitude  Trapped 
Particle  Eluxes  with  the  NASA  Models  AP-8  and  AE-8,”  Radiation  Measurements,  Vol.  26, 
pp.  947-952,  1996. 

Heynderickx,  D.,  private  communication.  May  2013. 


Approved  for  public  release;  distribution  is  unlimited. 

33 


Appendix  A:  Legacy  Models  AE8/AP8  and  CRRESELE/PRO-specific  parameters 

These  legaey  model  parameters  are  to  be  used  along  with  the  standard  orbital  speeification  parameters,  and  optionally  with  the  Dose 
calculation  parameters. 
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REActLvl  AESorAPS:  'min'/max'  Required*  none  Activity  Level  (*except  for  CRRESELE) 
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Appendix  B:  Legacy  Model  CAMMICE/MICS-specific  parameters 

These  CAMMICE/MICS  model  parameters  are  to  be  used  along  with  the  standard  orbital  speeifioation  parameters.  No  energy  level 
speeifieations  are  needed  -  values  are  always  output  for  the  twelve  pre-defmed  energy  bins  (1.0-1. 3,  1. 8-2.4,  3. 2-4.2,  5. 6-7. 4,  9.9-13.2, 
17.5-23.3,  30.9-41.1,  54.7-72.8,  80.3-89.7,  100.1-111.7,  124.7-139.1,  155.3-193.4  keV).  Dose  ealeulation  parameters  may  also  be  speeified 
for  the  CAMMICE/MICS  model,  but  will  generally  produee  non-zero  dose  results  only  for  the  top  three  energy  bins  (>0.1MeV). 
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Appendix  C:  Modified  Julian  Date 
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An  important  warning  for  users  of  SPENVIS  -  a  NON-STANDARD  definition  for  ‘Modified  Julian  Date’  is  used; 
“Finally,  note  that  the  Modified  Julian  Date  (MJD)  used  in  SPENVIS  is  defined  as  the  number  of  days  from  1st  January  1950  00:00  UT.  ’’ 
see  http://www.spenvis.oma.be/help/models/sapre.html 
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